<?php

namespace app\common\model;

use OpenApi\Attributes as OA;

#[OA\Schema(
    schema: 'SuccessResponse',
    title: "通用成功响应",
    description: "请求成功的标准返回结构",
    properties: [
        new OA\Property(property: "success", description: "请求是否成功", type: "boolean", example: true),
        new OA\Property(property: "code", description: "业务状态码，成功时通常为200", type: "integer", example: 200),
        new OA\Property(property: "message", description: "提示信息", type: "string", example: "操作成功"),
        new OA\Property(property: "data", description: "业务数据，可以是任意类型", type: "object", example: [], nullable: true)
    ],
    type: "object",
)]

#[OA\Schema(
    schema: 'ErrorResponse',
    title: "通用错误响应",
    description: "请求失败或出错的标准返回结构",
    properties: [
        new OA\Property(property: "success", description: "请求是否成功", type: "boolean", example: false),
        new OA\Property(property: "code", description: "业务状态码，错误时通常为非0值", type: "integer", example: 20001),
        new OA\Property(property: "message", description: "错误提示信息", type: "string", example: "操作失败"),
        new OA\Property(property: "data", description: "错误详情数据，可以是任意类型", type: "object", example: [], nullable: true)
    ],
    type: "object",
)]

#[OA\Schema(
    schema: 'PaginationData',
    title: "分页数据结构",
    description: "用于包裹分页列表的数据结构",
    properties: [
        new OA\Property(property: "total", description: "总记录数", type: "integer", example: 100),
        new OA\Property(property: "per_page", description: "每页记录数", type: "integer", example: 10),
        new OA\Property(property: "current_page", description: "当前页码", type: "integer", example: 1),
        new OA\Property(property: "last_page", description: "最后一页的页码", type: "integer", example: 10),
        new OA\Property(property: "has_more", description: "是否还有更多数据", type: "boolean", example: true),
        new OA\Property(property: "data", description: "当前页的数据列表", type: "array", items: new OA\Items()),
    ],
    type: "object"
)]

#[OA\Schema(
    schema: 'PaginatedResponse',
    title: "通用分页响应",
    description: "请求分页数据的通用API响应结构",
    allOf: [
        new OA\Schema(ref: "#/components/schemas/SuccessResponse"),
        new OA\Schema(
            properties: [
                new OA\Property(
                    property: "data",
                    ref: "#/components/schemas/PaginationData",
                    description: "分页数据详情"
                )
            ],
            type: "object"
        )
    ]
)]


#[OA\Response(
    response: 401,
    description: "未授权或Token失效",
    content: new OA\JsonContent(ref: "#/components/schemas/ErrorResponse")
)]
#[OA\Response(
    response: 500,
    description: "服务器内部错误",
    content: new OA\JsonContent(ref: "#/components/schemas/ErrorResponse")
)]

class ApiResponse
{
// 这个类本身不需要任何方法，它只是一个用于承载注解的容器。
}